<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <meta name="apple-mobile-web-app-capable" content="yes" />
        <meta name="apple-mobile-web-app-status-bar-style" content="black" />
        <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1.0, maximum-scale=1.0, minimal-ui" />
        
        <title>Listbox Documentation</title>
        
        <script src="/js/greyspots.js" type="text/javascript"></script>
        <link href="/css/greyspots.css" type="text/css" rel="stylesheet" />
        
        <script src="/js/ace/ace.js" data-ace-base="/js/ace/" type="text/javascript" charset="utf-8"></script>
        <script src="/js/ace/ext-language_tools.js" type="text/javascript"></script>
        <script src="/js/ace/ext-searchbox.js" type="text/javascript"></script>
        
        <script src="doc-library/doc.js" type="text/javascript"></script>
        <link href="doc-library/doc.css" type="text/css" rel="stylesheet" />
    </head>
    <body>
        <gs-jumbo>
            <h1 class="text-center">Listbox</h1>
        </gs-jumbo>
            
        <gs-container min-width="sml;med;lrg">
            <h3 class="doc-header">Tag:</h3>
            <pre><code>&lt;gs-listbox&gt;&lt;/gs-listbox&gt;</code></pre>
            
            <h3 class="doc-header">Description:</h3>
            <div class="doc-section">
                <p>Listboxes are similar to option boxes in that there is a list and one item from the list can be selected at any given time. Some of the differences are that the listbox can load data from the database, it tries to display full height and it can have a custom template.</p>
            </div>
            
            <h1 class="doc-header">Examples:</h1>
            <div class="doc-section">
                <div class="doc-example-description">
                    <span class="h3">Skeleton Example:</span>
                    <p>A basic <code>&lt;gs-listbox&gt;</code> element with a view source. The minimum <code>&lt;gs-listbox&gt;</code> will have the following behaviors:</p>
                    <ol>
                        <li>Column names are pulled from the database.</li>
                        <li>Selecting a record will highlight it.</li>
                    </ol>
                </div>
                <gs-doc-example>
                    <template for="html">
                        <gs-listbox src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[onchange=""]</code>:</span>
                    <p>To run javascript when the value changes, use the <code>[onchange=""]</code> attribute.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="15">
                        <label for="control_default">Change Alert:</label>
                        <gs-listbox id="control_default" src="gsdoc.tpeople_list" onchange="alert('value changed')"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[tabindex=""]</code>:</span>
                    <p>With the <code>[tabindex=""]</code> attribute, you can control what order your controls are tabbed to.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="25">
                        <label for="control_1">1:</label>
                        <gs-text tabindex="1" id="control_1"></gs-text>
                        <label for="control_3">3:</label>
                        <gs-text tabindex="3" id="control_3"></gs-text>
                        <label for="control_2">2:</label>
                        <gs-text tabindex="2" id="control_2"></gs-text>
                        <gs-listbox tabindex="3" style="height: 10ex;">
                            <template>
                                <table>
                                    <tbody>
                                        <tr><td>value 1</td></tr>
                                        <tr value="hidden value"><td>value 2</td></tr>
                                        <tr><td>value 3</td></tr>
                                        <tr><td>value 4</td></tr>
                                    </tbody>
                                </table>
                            </template>
                        </gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Static List Example:</span>
                    <p>Sometimes you only want to have a static list, this can be done with a template element inside the listbox. The template needs to contain an HTML table. To have a hidden value: put the hidden value in the <code>[value=""]</code> attribute of the <code>&lt;tr&gt;</code> element.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="auto">
                        <gs-listbox>
                            <template>
                                <table>
                                    <tbody>
                                        <tr><td>value 1</td></tr>
                                        <tr value="hidden value"><td>value 2</td></tr>
                                        <tr><td>value 3</td></tr>
                                        <tr><td>value 4</td></tr>
                                        <tr><td>value 5</td></tr>
                                        <tr><td>value 6</td></tr>
                                    </tbody>
                                </table>
                            </template>
                        </gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribue <code>[cols=""]</code>:</span>
                    <p>Sometimes you only want certain columns, using the <code>[cols=""]</code> attribute allows you to specify just the columns you want. Both examples have the same behavior.</p>
                </div>
                <gs-doc-example>
                    <template for="html">
                        <gs-listbox cols="name,age" src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[where=""]</code>:</span>
                    <p>You can specify a PostgreSQL <code>WHERE</code> clause using <code>[where=""]</code>.</p>
                </div>
                <gs-doc-example>
                    <template for="html">
                        <gs-listbox where="id=2316" src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[ord=""]</code>:</span>
                    <p>You can specify a PostgreSQL <code>ORDER BY</code> clause using <code>[ord=""]</code>.</p>
                </div>
                <gs-doc-example>
                    <template for="html">
                        <gs-listbox ord="age DESC" src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attributes <code>[limit=""]</code> & <code>[offset=""]</code>:</span>
                    <p>You can specify a PostgreSQL <code>LIMIT</code> and <code>OFFSET</code> clause using <code>[limit=""]</code> and <code>[offset=""]</code>.</p>
                </div>
                <gs-doc-example>
                    <template for="html">
                        <gs-listbox offset="5" limit="5" src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Custom Template Example:</span>
                    <p>In this example we are specifing a custom template for the listbox to use. This allows you to have more control over the look of your listbox. Notice: the <code>[value=""]</code> attribute on the <code>&lt;tr&gt;</code> element will be what you get when you get the value of the listbox; If you don't set the <code>[value=""]</code> attribute on the <code>&lt;tr&gt;</code> than the value will be the text of first column.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="auto">
                        <gs-listbox src="gsdoc.tpeople">
                            <template>
                                <table>
                                    <tbody>
                                        <tr value="{{! row.id }}">
                                            <td>
                                                {{! row.first_name }}
                                                {{! row.last_name }}
                                                {{! row.age }}
                                            </td>
                                        </tr>
                                    </tbody>
                                </table>
                            </template>
                        </gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[value=""]</code>:</span>
                    <p>You can specify the default selected record using the <code>[value=""]</code> attribute.</p>
                </div>
                <gs-doc-example>
                    <template for="html">
                        <gs-listbox value="2316" src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[qs=""]</code>:</span><br />
                    <p>The name <code>[qs]</code> stands for "querystring". The querystring is the part in the URL after the "?". The <code>[qs]</code> attribute has two formats, each with their own use.</p>
                    
                    <ul>
                        <li>qs="<i>key1</i>=<i>attribute1</i>". This format allows you to fill any attribute with any key from the querystring. To use multiple keys from the querystring you can put a comma-separated list of these expressions (for example: qs="<i>key1</i>=<i>attribute1</i>,<i>key2</i>=<i>attribute2</i>"). If you need an attribute to be added when a querystring key is not present, replace the "=" with "!=" (for example: qs="<i>key1</i>!=<i>attribute1</i>", attribute1 will only be added if key1 is not in the querystring). As a shorthand, if the key in the querystring is the same name as the attribute you want to fill, you can omit the attribute name in the expression (for example: qs="<i>key1</i>="). If an expression doesn't find it's key in the querystring: it reverts the attribute that it fills to it's original value.</li>
                        <li>qs="<i>key</i>". This format will update the <code>[value]</code> attribute with the querystring whenever the querystring changes.</li>
                    </ul>
                </div>
                <gs-doc-example query-string="test1=2319&test2=2317">
                    <template for="html" height="35">
                        <gs-listbox style="height: 7em;" qs="test1">
                            <template>
                                <table>
                                    <tbody>
                                        <tr><td>2317</td><td>test1</td></tr>
                                        <tr><td>2318</td><td>test1</td></tr>
                                        <tr><td>2319</td><td>test1</td></tr>
                                    </tbody>
                                </table>
                            </template>
                        </gs-listbox>
                        <gs-listbox style="height: 7em;" qs="test2=value">
                            <template>
                                <table>
                                    <tbody>
                                        <tr><td>2317</td><td>test2</td></tr>
                                        <tr><td>2318</td><td>test2</td></tr>
                                        <tr><td>2319</td><td>test2</td></tr>
                                    </tbody>
                                </table>
                            </template>
                        </gs-listbox>
                        <gs-listbox style="height: 7em;" qs="test3=hidden">
                            <template>
                                <table>
                                    <tbody>
                                        <tr><td>2317</td><td>test3</td></tr>
                                        <tr><td>2318</td><td>test3</td></tr>
                                        <tr><td>2319</td><td>test3</td></tr>
                                    </tbody>
                                </table>
                            </template>
                        </gs-listbox>
                        <gs-listbox style="height: 7em;" qs="test4!=hidden">
                            <template>
                                <table>
                                    <tbody>
                                        <tr><td>2317</td><td>test4</td></tr>
                                        <tr><td>2318</td><td>test4</td></tr>
                                        <tr><td>2319</td><td>test4</td></tr>
                                    </tbody>
                                </table>
                            </template>
                        </gs-listbox>
                        <br>
                        <br>
                        <gs-grid widths="1,1">
                            <gs-block>
                                <gs-button onclick="GS.pushQueryString('test1=2317');">Add "test1"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.removeFromQueryString('test1');">Remove "test1"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.pushQueryString('test2=2318');">Add "test2"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.removeFromQueryString('test2');">Remove "test2"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.pushQueryString('test3=yes');">Add "test3"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.removeFromQueryString('test3');">Remove "test3"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.pushQueryString('test4=yes');">Add "test4"</gs-button>
                            </gs-block>
                            <gs-block>
                                <gs-button onclick="GS.removeFromQueryString('test4');">Remove "test4"</gs-button>
                            </gs-block>
                        </gs-grid>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[disabled]</code>:</span>
                    <p>You can prevent selection and grey out the <code>&lt;gs-listbox&gt;</code> using the <code>[disabled]</code> attribute.</p>
                </div>
                <gs-doc-example>
                    <template for="html">
                        <gs-listbox disabled src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[no-select]</code>:</span>
                    <p>You can prevent selection using the <code>[no-select]</code> attribute.
                </div>
                <gs-doc-example>
                    <template for="html">
                        <gs-listbox no-select src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[letter-scrollbar]</code>:</span>
                    <p>For large listboxes, you can add a scrollbar composed of letters. When you click on a letter, it skips to the first record that begins with that letter. (This only works for the first column. We hid the id column so that it would use the first_name.) Typically you would sort on the first column as well.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="15">
                        <gs-listbox ord="name ASC" hide="id" letter-scrollbar src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Attribute <code>[letter-dividers]</code>:</span>
                    <p>You can also add a divider wherever the first letter changes. This can be used with the <code>[letter-scrollbar]</code> attribute.</p>
                </div>
                <gs-doc-example>
                    <template for="html" height="15">
                        <gs-listbox letter-dividers ord="name ASC" hide="id" src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Letter Scrollbar and Dividers Example:</span>
                    <p>Typical example of both <code>[letter-scrollbar]</code> and <code>[letter-dividers]</code></p>
                </div>
                <gs-doc-example>
                    <template for="html" height="15">
                        <gs-listbox letter-scrollbar letter-dividers ord="name ASC" hide="id" src="gsdoc.tpeople_list"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Refresh On Query String Column Change:</span>
                    <p>If you want to refresh on changes to a list of columns you can put a comma seperated list of columns in the <code>[refresh-on-querystring-values=""]</code> attribute. That could look something like <code>[refresh-on-querystring-values="parent_id,id"]</code>.</p>
                </div>
                <gs-doc-example query-string="id=2341&parent_id=test&asdf=changing_this_wont_refresh_the_listbox">
                    <template for="html" height="15">
                        <gs-listbox src="gsdoc.tpeople_list" qs="id" refresh-on-querystring-values="parent_id,id"></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Refresh On Query String Change:</span>
                    <p>To make the <code>&lt;gs-listbox&gt;</code> refresh when anything in the query string is updated, you add the attribute <code>[refresh-on-querystring-change]</code>.</p>
                </div>
                <gs-doc-example query-string="test=2341&asdf=changing_this_will_refresh_the_listbox">
                    <template for="html" height="15">
                        <gs-listbox src="gsdoc.tpeople_list" qs="test" refresh-on-querystring-change></gs-listbox>
                    </template>
                </gs-doc-example>
                
                <div class="doc-example-description">
                    <span class="h3">Javascript Methods:</span>
                    <p>These functions that can be run on individual <code>&lt;gs-listbox&gt;</code> elements:<br />
                    <i>LISTBOX</i>.refresh() &lt;-- This method refeshes the <code>&lt;gs-listbox&gt;</code>.<br />
                    <i>LISTBOX</i>.scrollToSelectedRecord() &lt;-- This method scrolls the <code>&lt;gs-listbox&gt;</code> to the currently selected record.<br />
                </div>
                
                <gs-doc-example>
                    <template for="html" height="15">
                        <gs-button onclick="testrefresh()">Refresh Listbox</gs-button>
                        <gs-button onclick="testscrollToSelectedRecord()">Scroll to Selected Record</gs-button>
                        <br />
                        <gs-listbox style="height: 30ex;" src="gsdoc.tpeople_list" id="test-elem"></gs-listbox>
                    </template>
                    <template for="js" height="15">
                        function testrefresh() {
                            document.getElementById('test-elem').refresh();
                        }
                        function testscrollToSelectedRecord() {
                            document.getElementById('test-elem').scrollToSelectedRecord();
                        }
                    </template>
                </gs-doc-example>
                
            </div>
        </gs-container>
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
        <br />
    </body>
</html>
